<html>
<head>
<title>HTTP over XMPP transport</title>
<link rel="stylesheet" type="text/css" href="style.css" />
</head>

<body>

<div class="header">HTTP over XMPP transport</div><p>

Allows to transport HTTP communication over XMPP peer-to-peer networks.<p>

<ul>
  <li><a href="#disco">Discover HOXT support</a></li>
  <li><a href="#iqexchange">IQ exchange</a></li>
</ul>

<hr>

<div class="subheader"><a name="disco">Discover HOXT support</a></div><p>

<b>Description</b><p>

Before using this extension you must ensure that your counterpart supports it also.</p>

<b>Usage</b><p>

<p>Once you have your <i><b>ServiceDiscoveryManager</b></i> you will be able to discover information associated with
an XMPP entity. To discover the information of a given XMPP entity send <b>discoverInfo(entityID)</b>
to your <i><b>ServiceDiscoveryManager</b></i> where entityID is the ID of the entity. The message
<b>discoverInfo(entityID)</b> will answer an instance of <i><b>DiscoverInfo</b></i> that contains
the discovered information.</p>

<b>Examples</b><p>

In this example we can see how to check if the counterpart supports HOXT: <br>
<blockquote>
<pre>      <font color="#3f7f5f">// Obtain the ServiceDiscoveryManager associated with my XMPPConnection</font>
      ServiceDiscoveryManager discoManager = ServiceDiscoveryManager.getInstanceFor(connection);

      <font color="#3f7f5f">// Get the information of a given XMPP entity</font>
      DiscoverInfo discoInfo = discoManager.discoverInfo("juliet@capulet.com");

      <font color="#3f7f5f">// Check if room is HOXT is supported</font>
      discoInfo.containsFeature("urn:xmpp:http");
</pre>
</blockquote>

<hr>

<div class="subheader"><a name="iqexchange">IQ exchange</a></div><p>

<b>Description</b><p>

You can use IQ's to perform HTTP requests and responses.
This is applicable to relatively short requests and responses (due to limitation of XMPP message size).</p>

<b>Usage</b><p>

<p>First you need to register a <i><b>PacketListener</b></i> to be able to handle intended IQs.<p>
For the HTTP client you:
<ul>
  <li>You create and send <i><b>HttpOverXmppReq</b></i> request.</li>
  <li>Then you handle the <i><b>HttpOverXmppResp</b></i> response in your <i><b>PacketListener</b></i>.</li>
</ul>

For the HTTP server you:
<ul>
    <li>You handle the <i><b>HttpOverXmppReq</b></i> requests in your <i><b>PacketListener</b></i>.</li>
    <li>And create and send <i><b>HttpOverXmppResp</b></i> responses.</li>
</ul>

</p>

<b>Examples</b><p>

In this example we are HTTP client, so we send request (POST) and handle the response: <br>
<blockquote>
<pre>      <font color="#3f7f5f">// register listener for IQ packets</font>
      connection.addPacketListener(new IqPacketListener(), new PacketTypeFilter(IQ.class));

      <font color="#3f7f5f">// create a request body</font>
      String urlEncodedMessage = "I_love_you";

      <font color="#3f7f5f">// create request</font>
      HttpOverXmppReq.Req req = new HttpOverXmppReq.Req(HttpMethod.POST, "/mailbox");
      req.setVersion("1.1");

      <font color="#3f7f5f">// prepare headers</font>
      Set&lt;Header&gt; set = new HashSet&lt;Header&gt;();
      set.add(new Header("Host", "juliet.capulet.com"));
      set.add(new Header("Content-Type", "application/x-www-form-urlencoded"));
      set.add(new Header("Content-Length", Integer.toString(urlEncodedMessage.length())));
      req.setHeaders(new HeadersExtension(set));

      <font color="#3f7f5f">// provide body or request (not mandatory, - empty body is used for GET)</font>
      AbstractHttpOverXmpp.Text child = new AbstractHttpOverXmpp.Text(urlEncodedMessage);
      AbstractHttpOverXmpp.Data data = new AbstractHttpOverXmpp.Data(child);
      req.setData(data);

      <font color="#3f7f5f">// create IQ packet</font>
      HttpOverXmppReq packet = new HttpOverXmppReq();
      packet.setReq(req);
      packet.setTo("juliet@capulet.com/balcony");
      packet.setType(IQ.Type.SET);
      packet.setPacketID("42");

      <font color="#3f7f5f">// send it</font>
      connection.sendPacket(packet);


      <font color="#3f7f5f">// then in your PacketListener</font>
      private class IqPacketListener implements PacketListener {

            @Override
            public void processPacket(Packet packet) {
                  IQ iq = (IQ) packet;

                  <font color="#3f7f5f">// verify from and packed ID</font>
                  if (iq.getFrom().equals("juliet@capulet.com/balcony") && (iq.getPacketID().equals("42"))) {

                        <font color="#3f7f5f">// ensure it's not ERROR</font>
                        if (iq.getType().equals(IQ.Type.RESULT)) {

                              <font color="#3f7f5f">// check if correct IQ implementation arrived</font>
                              if (iq instanceof HttpOverXmppResp) {
                                    HttpOverXmppResp resp = (HttpOverXmppResp) iq;

                                    <font color="#3f7f5f">// check HTTP response code</font>
                                    if (resp.getResp().getStatusCode() == 200) {

                                          <font color="#3f7f5f">// get content of the response</font>
                                          AbstractHttpOverXmpp.DataChild child = resp.getResp().getData().getChild();

                                          <font color="#3f7f5f">// check which type of content of the response arrived</font>
                                          if (child instanceof AbstractHttpOverXmpp.Xml) {

                                                <font color="#3f7f5f">// print the message and anxiously read if from console ;)</font>
                                                System.out.println(((AbstractHttpOverXmpp.Xml) child).getText());
                                          } else {
                                                <font color="#3f7f5f">// process other AbstractHttpOverXmpp.DataChild subtypes</font>
                                          }
                                    }
                              }
                        }
                  }
            }
      }
</pre>
</blockquote>

<hr>

</body>

</html>
